<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Numbers -->
.c
<!-- TRUE and FALSE omitted; unclear why LMNUC thinks they belong here. -->
<!-- FALSE at least does not seem to be on SYSTEM package. -->
.c
<!-- Missing explanation of the random number algorithm.  -->
.c
<div class='chapter'>4. Numbers</div><p class='cindent' id='number'><!-- number -->
Lisp Machine Lisp includes several types of numbers, with different
characteristics.  Most numeric functions will accept any type of numbers as
arguments and do the right thing.  That is to say, they are <font class="italic">generic</font>.
In Maclisp, there are generic numeric functions (like <font class="lisp">plus</font>) and there
are specific numeric functions (like <font class="lisp">+</font>) which only operate on a certain
type.  In Lisp Machine Lisp, this distinction does not exist; both function
names exist for compatibility but they are identical.  The microprogrammed
structure of the machine makes it possible to have only the generic
functions without loss of efficiency. 

The types of numbers in Lisp Machine Lisp are:
.table 1
.item fixnum
Fixnums are 24-bit 2's complement binary integers.  These are the "preferred,
most efficient" type of number.
.item bignum
Bignums are arbitrary-precision binary integers.
.item flonum
Flonums are floating-point numbers.  They have a mantissa of 32 bits and an exponent
of 11 bits, providing a precision of about 9 digits and a range of about 10^300.
Stable rounding is employed.
.item small-flonum
Small flonums are another form of floating-point number, with a mantissa of
18 bits and an exponent of 7 bits, providing a precision of about 5 digits
and a range of about 10^19.  Small flonums are useful because, like fixnums,
they don't require any storage.  Computing with small flonums is
more efficient than with regular flonums.
.end_table

Numbers are different from other objects in that they don't "have
identity." To put it another way, <font class="lisp">eq</font> does not work on them.
Numbers do not behave "like objects." Fixnums and small flonums are
exceptions to this rule; some system code knows that <font class="lisp">eq</font> works on
fixnums used to represent characters or small integers, and uses
<font class="lisp">memq</font> or <font class="lisp">assq</font> on them.

The Lisp machine automatically converts between fixnums and bignums
as necessary when computing with integers.  That is, if the result
of a computation with fixnums is too large to be represented as a fixnum,
it will be represented as a bignum.  If the result of a computation
with bignums is small enough to be represented as a fixnum, it will be.

The Lisp machine never automatically converts between flonums and small
flonums, since this would lead  either to inefficiency or to unexpected
numerical inaccuracies.  The user controls whether floating-point
calculations are done in large or small precision by the type of the
original input data.

Integer computations cannot "overflow", except for division by zero,
since bignums can be of arbitrary size.  Floating-point computations
can get exponent overflow or underflow, if the result is too large or small
to be represented.  This will signal an error.

When an arithmetic function of more than one argument is given arguments of
different numeric types, uniform <font class="italic">coercion rules</font> are followed to convert
the arguments to a common type, which is also the type of the result (for
functions which return a number).  When a fixnum meets a bignum, the result
is (usually) a bignum.  When a fixnum or a bignum meets a small flonum or a flonum,
the result is a small flonum or a flonum (respectively).  When a small flonum
meets a regular flonum, the result is a regular flonum.

Unlike Maclisp, Lisp Machine Lisp does not have number declarations in the compiler.
Note that because fixnums and small flonums are "inums" (require no associated
storage) they are as efficient as declared numbers in Maclisp.

The different types of numbers are distinguished by their printed
representations.  A leading or embedded decimal point, and/or an exponent
separated by "e", indicates a flonum.  If a number has an exponent
separated by "s", it is a small flonum.  Small flonums require a special
indicator so that naive users will not be accidentally tricked into
computing with the lesser precision.  Fixnums and bignums have similar
printed representations; the number is a bignum if it is too big to be a
fixnum. 

<div class='section'>4.1 Numeric Predicates</div><div class='defun'><font class='exdent'><font class='funcname'>zerop <font class='italic' color='purple'>x</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">x</font> is zero.  Otherwise it returns <font class="lisp">nil</font>.
If <font class="italic">x</font> is not a number, <font class="lisp">zerop</font> causes an error.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>plusp <font class='italic' color='purple'>x</font></font></font><br>
Returns <font class="lisp">t</font> if its argument is a positive number, strictly greater
than zero.  Otherwise it returns <font class="lisp">nil</font>.
If <font class="italic">x</font> is not a number, <font class="lisp">plusp</font> causes an error.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>minusp <font class='italic' color='purple'>x</font></font></font><br>
Returns <font class="lisp">t</font> if its argument is a negative number, strictly
less than zero.  Otherwise it returns <font class="lisp">nil</font>.
If <font class="italic">x</font> is not a number, <font class="lisp">minusp</font> causes an error.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>oddp <font class='italic' color='purple'>number</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">number</font> is odd, otherwise <font class="lisp">nil</font>.
If <font class="italic">number</font> is not a fixnum or a bignum, <font class="lisp">oddp</font> causes an error.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>evenp <font class='italic' color='purple'>number</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">number</font> is even, otherwise <font class="lisp">nil</font>.
If <font class="italic">number</font> is not a fixnum or a bignum, <font class="lisp">evenp</font> causes an error.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>signp</font><font class="italic"> Special Form</font></font><br>
<font class="italic">signp</font> is used to test the sign of a number.  It is present
only for Maclisp compatibility, and is not recommended for use in new
programs.  <font class="lisp">(signp <font class="italic">test x</font>)</font> returns <font class="lisp">t</font> if <font class="italic">x</font> is a number
which satisfies the <font class="italic">test</font>, <font class="lisp">nil</font> if it is not.  <font class="italic">test</font> is not
evaluated, but <font class="italic">x</font> is.
<font class="italic">test</font> can be one of the following:
.table 3 500 250 0 0
.item l
x &lt; 0
.item le
x  0
.item e
x = 0
.item n
x  0
.item ge
x  0
.item g
x &gt; 0
.end_table
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(signp le 12) =&gt; t
(signp n 0) =&gt; nil
(signp g 'foo) =&gt; nil
</pre>
</div>

See also the data-type predicates <font class="lisp">fixp</font>, <font class="lisp">floatp</font>, <font class="lisp">bigp</font>,
<font class="lisp">small-floatp</font>, and <font class="lisp">numberp</font> ((fixp-fun)).

All of these functions require that their arguments be numbers, and signal
an error if given a non-number.  They work on all types of numbers,
automatically performing any required coercions.

<div class='defun'><font class='exdent'><font class='funcname'>= <font class='italic' color='purple'>x y</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">x</font> and <font class="italic">y</font> are numerically equal.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>greaterp <font class='italic' color='purple'>x y &rest more-args</font></font></font><br>
<font class="lisp">greaterp</font> compares its arguments from left to right.  If any argument
is not greater than the next, <font class="lisp">greaterp</font> returns <font class="lisp">nil</font>.  But if the
arguments are monotonically strictly decreasing, the result is <font class="lisp">t</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(greaterp 4 3) =&gt; t
(greaterp 4 3 2 1 0) =&gt; t
(greaterp 4 3 1 2 0) =&gt; nil
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>&gt; <font class='italic' color='purple'>x y</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">x</font> is strictly greater than <font class="italic">y</font>, and <font class="lisp">nil</font>
otherwise.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='>= x y'>>= x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br></div><div class='defmac'><font class='exdent'><font class='funcname' id=' x y'> x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Returns <font class="lisp">t</font> if <font class="italic">x</font> is greater than or equal to <font class="italic">y</font>, and <font class="lisp">nil</font>
otherwise.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>lessp <font class='italic' color='purple'>x y &rest more-args</font></font></font><br>
<font class="lisp">lessp</font> compares its arguments from left to right.  If any argument
is not less than the next, <font class="lisp">lessp</font> returns <font class="lisp">nil</font>.  But if the
arguments are monotonically strictly increasing, the result is <font class="lisp">t</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(lessp 3 4) =&gt; t
(lessp 1 1) =&gt; nil
(lessp 0 1 2 3 4) =&gt; t
(lessp 0 1 3 2 4) =&gt; nil
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>&lt; <font class='italic' color='purple'>x y</font></font></font><br>
Returns <font class="lisp">t</font> if <font class="italic">x</font> is strictly less than <font class="italic">y</font>, and <font class="lisp">nil</font>
otherwise.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='<= x y'><= x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br></div><div class='defmac'><font class='exdent'><font class='funcname' id=' x y'> x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Returns <font class="lisp">t</font> if <font class="italic">x</font> is less than or equal to <font class="italic">y</font>, and <font class="lisp">nil</font>
otherwise.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id=' x y'> x y</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Returns <font class="lisp">t</font> if <font class="italic">x</font> is not equal to <font class="italic">y</font>, and <font class="lisp">nil</font> otherwise.
</div>

<div class='section'>4.2 Arithmetic</div>
All of these functions require that their arguments be numbers, and signal
an error if given a non-number.  They work on all types of numbers,
automatically performing any required coercions.

<div class='defun'><font class='exdent'><font class='funcname'>plus <font class='italic' color='purple'>&rest args</font></font></font><br>
.defun1 + &rest args
.defun1 +$ &rest args
Returns the sum of its arguments.  If there are no arguments, it returns
0, which is the identity for this operation.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>difference <font class='italic' color='purple'>arg &rest args</font></font></font><br>
Returns its first argument minus all of the rest of its arguments.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>- <font class='italic' color='purple'>arg &rest args</font></font></font><br>
.defun1 -$ arg &rest args
With only one argument, <font class="lisp">-</font> is the same as <font class="lisp">minus</font>; it
returns the negative of its argument.
With more than one argument, <font class="lisp">-</font> is the same as <font class="lisp">difference</font>;
it returns its first argument minus all of the rest of its arguments.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>times <font class='italic' color='purple'>&rest args</font></font></font><br>
.defun1 * &rest args
.defun1 *$ &rest args
Returns the product of its arguments.  If there are no arguments, it
returns 1, which is the identity for this operation.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>quotient <font class='italic' color='purple'>arg &rest args</font></font></font><br>
Returns the first argument divided by all of the rest of its arguments.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>// <font class='italic' color='purple'>arg &rest args</font></font></font><br>
.defun1 //$ arg &rest args
The name of this function is written <font class="lisp">//</font> rather than <font class="lisp">/</font> because
<font class="lisp">/</font> is the quoting character in Lisp syntax and must be doubled.
With more than one argument, <font class="lisp">//</font> is the same as <font class="lisp">quotient</font>;
it returns the first argument divided by all of the rest of its arguments.
With only one argument, <font class="lisp">(// <font class="italic">x</font>)</font> is the same as <font class="lisp">(// 1 <font class="italic">x</font>)</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(// 3 2) =&gt; 1       <font class="main">;Fixnum division truncates.</font>
(// 3 2.0) =&gt; 1.5
(// 3 2.0s0) =&gt; 1.5s0
(// 4 2) =&gt; 2
(// 12. 2. 3.) =&gt; 2
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>add1 <font class='italic' color='purple'>x</font></font></font><br>
.defun1 1+ x
.defun1 1+$ x
<font class="lisp">(add1 x)</font> is the same as <font class="lisp">(plus x 1)</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>sub1 <font class='italic' color='purple'>x</font></font></font><br>
.defun1 1- x
.defun1 1-$ x
<font class="lisp">(sub1 x)</font> is the same as <font class="lisp">(difference x 1)</font>.  Note that the
short name may be confusing: <font class="lisp">(1- x)</font> does <font class="italic">not</font> mean 1-x;
rather, it means x-1.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>remainder <font class='italic' color='purple'>x y</font></font></font><br>
.defun1 \ x y
Returns the remainder of <font class="italic">x</font> divided by <font class="italic">y</font>.
<font class="italic">x</font> and <font class="italic">y</font> may not be flonums nor small flonums.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>gcd <font class='italic' color='purple'>x y</font></font></font><br>
.defun1 \\ x y
Returns the greatest common divisor of <font class="italic">x</font> and <font class="italic">y</font>.
<font class="italic">x</font> and <font class="italic">y</font> may not be flonums nor small flonums.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>expt <font class='italic' color='purple'>x y</font></font></font><br>
.defun1 ^ x y
.defun1 ^$ x y
Returns <font class="italic">x</font> raised to the <font class="italic">y</font>'th power.  <font class="italic">y</font> must be a fixnum.
[I guess this is incompatible with Maclisp.]
</div>

<div class='defun'><font class='exdent'><font class='funcname'>exp <font class='italic' color='purple'>x</font></font></font><br>
Returns <font class="italic">e</font> raised to the <font class="italic">x</font>'th power, where <font class="italic">e</font> is the base of natural logarithms.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>log <font class='italic' color='purple'>x</font></font></font><br>
Returns the natural logarithm of <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>sin <font class='italic' color='purple'>x</font></font></font><br>
Returns the sine of <font class="italic">x</font> in radians.
</div>

<!-- bletch, do we want these in here? -->
<div class='defun'><font class='exdent'><font class='funcname'>sind <font class='italic' color='purple'>x</font></font></font><br>
Returns the sine of <font class="italic">x</font> in degrees.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>cos <font class='italic' color='purple'>x</font></font></font><br>
Returns the cosine of <font class="italic">x</font> in radians.
</div>

<!-- bletch do we want these in here? -->
<div class='defun'><font class='exdent'><font class='funcname'>cosd <font class='italic' color='purple'>x</font></font></font><br>
Returns the cosine of <font class="italic">x</font> in degrees.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>sqrt <font class='italic' color='purple'>x</font></font></font><br>
Returns the square root of <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>atan <font class='italic' color='purple'>y x</font></font></font><br>
Returns the arctangent of the angle <font class="italic">y/x</font>. It always returns a
non-negative number between zero and /2.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>atan2 <font class='italic' color='purple'>y x</font></font></font><br>
Returns the arctangent of the angle <font class="italic">y/x</font>, except that it returns a
number between -/2 and /2.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>max <font class='italic' color='purple'>&rest args</font></font></font><br>
<font class="lisp">max</font> returns the largest of its arguments.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(max 1 3 2) =&gt; 3
</pre>
<font class="lisp">max</font> requires at least one argument.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>min <font class='italic' color='purple'>&rest args</font></font></font><br>
<font class="lisp">min</font> returns the smallest of its arguments.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(min 1 3 2) =&gt; 1
</pre>
<font class="lisp">min</font> requires at least one argument.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>abs <font class='italic' color='purple'>x</font></font></font><br>
Returns <font class="lisp">|<font class="italic">x</font>|</font>, the absolute value of the number <font class="italic">x</font>.
<font class="lisp">abs</font> could have been defined by:
<pre class="lisp">
(defun abs (x)
    (cond ((minusp x) (minus x))
	  (t x)))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>minus <font class='italic' color='purple'>x</font></font></font><br>
Returns the negative of <font class="italic">x</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(minus 1) =&gt; -1
(minus -3) =&gt; 3
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>*dif <font class='italic' color='purple'>x y</font></font></font><br>
.defun1 *plus x y
.defun1 *quo x y
.defun1 *times x y
These are the internal micro-coded arithmetic functions.  There is no
reason why anyone should need to refer to these explicitly, since the
compiler knows how to generate the appropriate code for <font class="lisp">plus</font>,
<font class="lisp">+</font>, etc.  These names are only here for Maclisp compatibility.
</div>

The following functions are provided to allow specific conversions of data
types to be forced, when desired.

<div class='defun'><font class='exdent'><font class='funcname'>fix <font class='italic' color='purple'>x</font></font></font><br>
Converts <font class="italic">x</font> from a flonum (or small-flonum) to an integer, by truncation.
The result is a fixnum or a bignum as appropriate.  If <font class="italic">x</font> is already
a fixnum or a bignum, it is returned unchanged.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>fixr <font class='italic' color='purple'>x</font></font></font><br>
Converts <font class="italic">x</font> from a flonum (or small-flonum) to an integer, by truncation.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>float <font class='italic' color='purple'>x</font></font></font><br>
Converts <font class="italic">x</font> to a flonum.  <font class="italic">x</font> may be a fixnum, a bignum, a small-flonum,
or a flonum.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>small-float <font class='italic' color='purple'>x</font></font></font><br>
Converts <font class="italic">x</font> to a small flonum.  <font class="italic">x</font> may be a fixnum, a bignum, a small-flonum,
or a flonum.
</div>

<!-- Lots of trig functions missing as of this writing.  -->

<div class='section'>4.3 Random Functions</div>
<div class='defun'><font class='exdent'><font class='funcname'>random <font class='italic' color='purple'>&optional arg (array <font class="lisp">si:random-array</font>)</font></font></font><br>
<font class="lisp">(random)</font> returns a random fixnum, positive or negative.
If <font class="italic">arg</font> is present, a fixnum between 0 and <font class="italic">arg</font>-1 inclusive is returned.
If <font class="italic">array</font> is present, the given array is used instead of the default
one (see below).
[The random algorithm should be described.]
</div>

<div class='defun'><font class='exdent'><font class='funcname'>si:random-create-array <font class='italic' color='purple'>size offset seed &optional (area <font class="lisp">default-array-area</font>)</font></font></font><br>
Creates, initializes and returns a random-number-generator array.
This is used for more advanced applications of the pseudo-random
number generator, in which it is desirable to have several different
controllable resettable sources of random numbers.  For the exact
meaning of the arguments, read the code.
<!-- For now. -->
<font class="italic">size</font> is the size of the array, <font class="italic">offset</font> is an integer less than
<font class="italic">size</font>, <font class="italic">seed</font> is a fixnum.
This calls <font class="lisp">si:random-initialize</font> on the random array before returning it.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>si:random-initialize <font class='italic' color='purple'>array</font></font></font><br>
<font class="italic">array</font> must be a random-number-generator array, such as
is created by <font class="lisp">si:random-create-array</font>.  It reinitializes the
contents of the array from the seed (calling <font class="lisp">random</font> changes
the contents of the array and the pointers, but not the seed).
</div>

.defvar si:random-array
The value of <font class="lisp">si:random-array</font> is the default random-number-generator array.
It is created if <font class="lisp">random</font> is called and <font class="lisp">si:random-array</font> is unbound.
A random-number-generator array has a leader which is a structure with
the following elements:
.ftable 3
.item si:random-fill-pointer
The fill-pointer, the length of the array.
.item si:random-seed
The seed from which to initialize the contents.
.item si:random-pointer-1
The first pointer.
.item si:random-pointer-2
The second pointer.
.end_table
.end_defvar

<div class='section'>4.4 Logical Operations on Numbers</div>
Except for <font class="lisp">lsh</font> and <font class="lisp">rot</font>, these functions operate on either
fixnums or bignums.  <font class="lisp">lsh</font> and <font class="lisp">rot</font> have an inherent word-length
limitation and hence only operate on 24-bit fixnums.  Negative numbers
are operated on in their 2's-complement representation.  (Negative
numbers used to be disallowed in some cases.)

<div class='defun'><font class='exdent'><font class='funcname'>logior <font class='italic' color='purple'>&rest args</font></font></font><br>
Returns the bit-wise logical <font class="italic">inclusive or</font> of its arguments.
A minimum of one argument is required.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(logior 4002 67) =&gt; 4067
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>logxor <font class='italic' color='purple'>&rest args</font></font></font><br>
Returns the bit-wise logical <font class="italic">exclusive or</font> of its arguments.
A minimum of one argument is required.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(logxor 2531 7777) =&gt; 5246
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>logand <font class='italic' color='purple'>&rest args</font></font></font><br>
Returns the bit-wise logical <font class="italic">and</font> of its arguments.
A minimum of one argument is required.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(logand 3456 707) =&gt; 406
(logand 3456 -100) =&gt; 3400
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>boole <font class='italic' color='purple'>fn &rest args</font></font></font><br>
<font class="lisp">boole</font> is the generalization of <font class="lisp">logand</font>, <font class="lisp">logior</font>, and <font class="lisp">logxor</font>.
<font class="italic">fn</font> should be a fixnum between 0 and 17 octal inclusive;
it controls the function which is computed.  If the binary representation
of <font class="italic">fn</font> is <font class="italic">abcd</font> (<font class="italic">a</font> is the most significant bit, <font class="italic">d</font> the least)
then the truth table for the Boolean operation is as follows:
.sp
<pre class="lisp">
       y
   | 0  1
---------
  0| a  c
x  |
  1| b  d
</pre>

If <font class="lisp">boole</font> has more than three arguments, it is associated left
to right; thus,
<pre class="lisp">
(boole fn x y z) = (boole fn (boole fn x y) z)
</pre>
With two arguments, the result of <font class="lisp">boole</font> is simply its second argument.
A minimum of two arguments is required.

<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(boole 1 x y) = (logand x y)
(boole 6 x y) = (logxor x y)
</pre>

<font class="lisp">logand</font>, <font class="lisp">logior</font>, and <font class="lisp">logxor</font> are usually preferred over <font class="lisp">boole</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>bit-test <font class='italic' color='purple'>x y</font></font></font><br>
<font class="lisp">bit-test</font> is a predicate which returns <font class="lisp">t</font> if any of
the bits designated by the 1's in <font class="italic">x</font> are 1's in <font class="italic">y</font>.
<font class="lisp">bit-test</font> is implemented as a macro which expands as follows:
<pre class="lisp">
(bit-test <font class="italic">x</font> <font class="italic">y</font>) ==&gt; (not (zerop (logand <font class="italic">x</font> <font class="italic">y</font>)))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ldb-test <font class='italic' color='purple'>ppss y</font></font></font><br>
<font class="lisp">ldb-test</font> is a predicate which returns <font class="lisp">t</font> if any of
the bits designated by the byte specifier <font class="italic">ppss</font> are 1's in <font class="italic">y</font>.
That is, it returns <font class="lisp">t</font> if the designated field is non-zero.
<font class="lisp">ldb-test</font> is implemented as a macro which expands as follows:
<pre class="lisp">
(ldb-test <font class="italic">ppss</font> <font class="italic">y</font>) ==&gt; (not (zerop (ldb <font class="italic">ppss</font> <font class="italic">y</font>)))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>lsh <font class='italic' color='purple'>x y</font></font></font><br>
Returns <font class="italic">x</font> shifted left <font class="italic">y</font> bits if <font class="italic">y</font> is positive or zero,
or <font class="italic">x</font> shifted right <font class="lisp">|<font class="italic">y</font>|</font> bits if <font class="italic">y</font> is negative.
Zero bits are shifted in (at either end) to fill unused positions.
<font class="italic">x</font> and <font class="italic">y</font> must be fixnums.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(lsh 4 1) =&gt; 10    <font class="main">;(octal)</font>
(lsh 14 -2) =&gt; 3
(lsh -1 1) =&gt; -2
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>ash <font class='italic' color='purple'>x y</font></font></font><br>
Shifts <font class="italic">x</font> arithmetically left <font class="italic">y</font> bits, or right <font class="italic">-y</font> bits,
depending on the sign of <font class="italic">y</font>.  <font class="italic">x</font> may be a fixnum or a bignum.
The sign of the result is always the same as the sign of <font class="italic">x</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>rot <font class='italic' color='purple'>x y</font></font></font><br>
Returns <font class="italic">x</font> rotated left <font class="italic">y</font> bits if <font class="italic">y</font> is positive or zero,
or <font class="italic">x</font> rotated right <font class="lisp">|<font class="italic">y</font>|</font> bits if <font class="italic">y</font> is negative.
The rotation considers <font class="italic">x</font> as a 24-bit number (unlike Maclisp,
which considers <font class="italic">x</font> to be a 36-bit number in both the pdp-10
and Multics implementations).
<font class="italic">x</font> and <font class="italic">y</font> must be fixnums.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(rot 1 2) =&gt; 4
(rot 1 -2) =&gt; 20000000
(rot -1 7) =&gt; -1
(rot 15 24.) =&gt; 15
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>haipart <font class='italic' color='purple'>x n</font></font></font><br>
Returns the high <font class="italic">n</font> bits of the binary representation of <font class="lisp">|<font class="italic">x</font>|</font>,
or the low <font class="lisp">|<font class="italic">n</font>|</font> bits if <font class="italic">n</font> is negative.
<font class="italic">x</font> may be a fixnum or a bignum; note that if <font class="italic">x</font> is negative
its absolute value is used.
<!-- Is there a better description of this in the Maclisp manual? -->
</div>

<div class='defun'><font class='exdent'><font class='funcname'>haulong <font class='italic' color='purple'>x</font></font></font><br>
This returns the number of significant bits in <font class="italic">x</font>.  <font class="italic">x</font> may be a fixnum or a bignum.
The result does not depend on the sign of <font class="italic">x</font>.
The result is the least integer not less than the base-2 logarithm of <font class="lisp">|<font class="italic">x</font>|+1</font>.
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(haulong 0) =&gt; 0
(haulong 3) =&gt; 2
(haulong -7) =&gt; 3
</pre>
</div>

<div class='section'>4.5 Byte Manipulation Functions</div><p class='cindent'><!-- "byte" -->
Several functions are provided for dealing with an arbitrary-width field of
contiguous bits appearing anywhere in an integer (a fixnum or a bignum).
Such a contiguous set of bits is called a <font class="italic">byte</font>.  Note that
we are not using the term <font class="italic">byte</font> to mean eight bits, but rather
any number of bits within a number.
These functions use numbers called <font class="italic">byte specifiers</font> to
<p class='cindent'><!-- "byte specifiers" -->
designate a specific byte position within any word.  Byte specifiers are fixnums
whose two lowest octal digits represent the <font class="italic">size</font> of the
byte, and whose higher (usually two, but sometimes more)
octal digits represent the <font class="italic">position</font>
of the byte within a number, counting from the right in bits.  A position
of zero means that the byte is at the right end of the number.
For example, the byte-specifier 0010 (i.e., 10 octal) refers to the lowest 
eight bits of a word, and the byte-specifier 1010 refers to the next eight
bits.  These byte-specifiers will be stylized below as <font class="italic">ppss</font>.
<p class='cindent'><!-- "ppss" -->
The maximum value of the <font class="italic">ss</font> digits is 27 (octal), since a byte must
fit in a fixnum although bytes can be loaded from and deposited into bignums.
(Bytes are always positive numbers.)
The format of byte-specifiers is taken from the pdp-10 byte instructions.

<div class='defun'><font class='exdent'><font class='funcname'>ldb <font class='italic' color='purple'>ppss num </font></font></font><br>
<font class="italic">ppss</font> specifies a byte of <font class="italic">num</font>, which is returned as a number,
right-justified.  The <font class="italic">ss</font> bits of the byte starting at bit <font class="italic">pp</font>
are the lowest <font class="italic">ss</font> bits in the returned value, and the rest of the
bits in the returned value are zero.  The name of the function,
<font class="lisp">ldb</font>, means "load byte".  <font class="italic">num</font> may be a fixnum or a bignum.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(ldb 0306 4567) =&gt; 56
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>mask-field <font class='italic' color='purple'>ppss num</font></font></font><br>
This is similar to <font class="lisp">ldb</font>; however, the specified byte
of <font class="italic">num</font> is returned as a number in position <font class="italic">pp</font> of
the returned word, instead of position 0 as with <font class="lisp">ldb</font>.
<font class="italic">num</font> must be a fixnum.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(mask-field 0306 4567) =&gt; 560
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>dpb <font class='italic' color='purple'>byte ppss num</font></font></font><br>
Returns a number which is the same as <font class="italic">num</font> except in the
bits specified by <font class="italic">ppss</font>.  The low
<font class="italic">ss</font> bits of <font class="italic">byte</font> are placed in those bits.  <font class="italic">byte</font> is interpreted as
being right-justified, as if it were the result of <font class="lisp">ldb</font>.
<font class="italic">num</font> may be a fixnum or a bignum.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(dpb 23 0306 4567) =&gt; 4237
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>deposit-field <font class='italic' color='purple'>byte ppss num</font></font></font><br>
This is like <font class="lisp">dpb</font>, except that <font class="italic">byte</font> is not taken to
be left-justified; the <font class="italic">ppss</font> bits of <font class="italic">byte</font> are used
for the <font class="italic">ppss</font> bits of the result, with the rest of the
bits taken from <font class="italic">num</font>.  <font class="italic">num</font> must be a fixnum.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(deposit-field 230 0306 4567) =&gt; 4237
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%logldb <font class='italic' color='purple'>ppss fixnum</font></font></font><br>
<font class="lisp">%logldb</font> is like <font class="lisp">ldb</font> except that it only loads out of fixnums and
allows a byte size of 30 (octal), i.e. the whole fixnum.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%logdpb <font class='italic' color='purple'>byte ppss fixnum</font></font></font><br>
<font class="lisp">%logdpb</font> is like <font class="lisp">dpb</font> except that it only deposits into fixnums.
Using this to change the sign-bit will leave the result as a fixnum,
while <font class="lisp">dpb</font> would produce a bignum result for arithmetic correctness.
<font class="lisp">%logdpb</font> is good for manipulating fixnum bit-masks such as are used
in some internal system tables and data-structures.
</div>

<div class='section'>4.6 24-Bit Numbers</div>Sometimes it is desirable to have a form of arithmetic which has no
overflow checking (which would produce bignums),
and truncates results to the word size of the machine.
In Lisp Machine Lisp, this is provided by the following set of functions.
Their answers are only correct modulo 2^24.
	These functions should <font class="italic">not</font> be used for "efficiency";
they are probably less efficient than the functions which <font class="italic">do</font> check for
overflow.  They are intended for algorithms which require this sort of
arithmetic, such as hash functions and pseudo-random number generation.

<div class='defun'><font class='exdent'><font class='funcname'>%24-bit-plus <font class='italic' color='purple'>x y</font></font></font><br>
Returns the sum of <font class="italic">x</font> and <font class="italic">y</font> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%24-bit-difference <font class='italic' color='purple'>x y</font></font></font><br>
Returns the difference of <font class="italic">x</font> and <font class="italic">y</font> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%24-bit-times <font class='italic' color='purple'>x y</font></font></font><br>
Returns the product of <font class="italic">x</font> and <font class="italic">y</font> modulo 2^24.  Both arguments should
be fixnums.
</div>

<div class='section'>4.7 Double-Precision Arithmetic</div>
These peculiar functions are useful in programs that don't want to use
bignums for one reason or another.

<div class='defun'><font class='exdent'><font class='funcname'>%multiply-fractions <font class='italic' color='purple'>num1 num2</font></font></font><br>
Returns bits 24 through 46 (the most significant half)
of the product of <font class="italic">num1</font> and <font class="italic">num2</font>.
If you call this and <font class="lisp">%24-bit-times</font> on the same arguments <font class="italic">num1</font>
and <font class="italic">num2</font>, regarding them as integers, you can combine
the results into a double-precision product.
If <font class="italic">num1</font> and <font class="italic">num2</font> are regarded as fractions, <font class="lisp">-1  <font class="italic">num</font> &lt; 1</font>,
<font class="lisp">%multiply-fractions</font> returns 1/2 of their correct product as a fraction.
(The name of this function isn't too great.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%divide-double <font class='italic' color='purple'>dividend[24:46] dividend[0:23] divisor</font></font></font><br>
Divides the double-precision number given by the first two
arguments by the third argument, and returns the single-precision
quotient.  Causes an error if division by zero or if the quotient won't
fit in single precision.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%remainder-double <font class='italic' color='purple'>dividend[24:46] dividend[0:23] divisor</font></font></font><br>
Divides the double-precision number given by the first two
arguments by the third argument, and returns the
remainder.  Causes an error if division by zero.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>%float-double <font class='italic' color='purple'>high24 low24</font></font></font><br>
<font class="italic">high24</font> and <font class="italic">low24</font>, which must be fixnums, are concatenated
to produce a 48-bit unsigned positive integer.  A flonum containing the
same value is constructed and returned.  Note that only the 31 most-significant
bits are retained (after removal of leading zeroes.)  This function is
mainly for the benefit of <font class="lisp">read</font>.
</div>

.eof
</body>
</html>

